COMMENT ⊗   VALID 00002 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	\begincom{def-generic-options}
C00014 ENDMK
C⊗;
\begincom{def-generic-options}

\label Purpose:

The macro {\bf def-generic-options} allows you to specify options and
declarations that pertain to a generic function as a whole.  If there is
no generic function associated with the symbol function cell of the symbol
that is the name of the generic function, a new generic function object is
created and stored in the symbol function cell.  The generic function
object is returned as the result.

\label Syntax:

(def-generic-options generic-function-name lambda-list {option}*)

option ::= (:documentation string) | string
           (:method-combination name {argument}*)
           (declare {declaration}+)
           (:argument-precedence-order {parameter-name}+)
           (:interface {form}+)
           (:method-arguments {form}+)
           (:generic-function-class class-name)
           (:method-class class-name) 

\Defmac {def-generic-options} {name lambda-list \ttbrac{documentation} \star{\curly{option}}}

{\it option\/}::$=$ {\tt\vtop{\hbox{(:argument-precedence-order {\it argument-precedence-order-list\/}) $\vert$}
\hbox{(:method-combination-type {\it symbol\/}) $\vert$}
\hbox{$\ldots$}}}

\label Arguments:

{\it generic-function-name} is a non-null symbol naming the generic function.

The {\it lambda-list\/} argument is an ordinary function lambda list
with these exceptions:

1.  No \&aux variables are allowed. 
2.  Optionals (including keyword arguments)may not have default-forms ur
    use supplied-p, and hence the symbol does not imply a default value
    of NIL.   Note that optionals in the methods can have default forms
    and supplied-p. 

The set of defined options is:

(:documentation string) | string
                Associates a documentation string with the generic
                function.  The form (documentation generic-function-name
                'function) retrieves this string.

(:method-combination name {argument}*)
                Indicates that the generic function uses the type of method
                combination named by name.  The arguments depend on the
                type of method combination.  The most common argument is
                one to specify the order of methods, which is either
                :most-specific-first or :most-specific-last.  The default
                method combination type is :daemon, with the
                :most-specific-first order.

(declare {declaration}+)
                Declarations that apply to the whole function (as opposed
                to declarations of variables) are permitted.  The only
                declaration in this standard is optimize, which can have
                the value of speed or space.  This allows the user to
                control whether method selection is optimized for speed or
                space; it has no affect on individual methods.  Some
                implementations might support other declarations.  If an
                implementation notices a declaration that it does not
                support, it should follow the rules described on page 161
                of Common Lisp the Language.

(:argument-precedence-order {parameter-name}+)
                This option alters the default way of selecting methods.
                By default, all required arguments are considered
                from left to right; each required argument has
                precedence over those to its right.  When this option is
                used, each required argument should be included as a
                parameter-name, so the full precedence order is supplied.

(:interface {form}+)
		This option is under discussion.
                Defines a function that runs instead of the generic
                dispatch.  This is completely transparent to anyone calling
                the generic function.  Such a prologue function can be used
                to rearrange the arguments, to standardize the arguments
                before the methods see them, to default optional arguments,
                to do the shared non-generic portion of an operation, or
                for any other purpose.  Another use of this option is to
                extend a generic function so it can also be used for
                objects that are not instances of a built-in class.

                Inside the forms you can trigger the generic dispatch with
                (call-methods args...) or (apply-methods args...).
                apply-methods treats the last argument as a list of
                arguments just like apply.  call-methods and apply-methods
                are defined lexically only inside the :interface option.

(:method-arguments {form}+)
		This option is under discussion. 
                You can use this option to specify that the methods accept
                different arguments than does the generic function itself.
                By default, the methods receive the same arguments that are
                specified at the top of the def-generic-options form.  The
                :method-arguments option is meaningful only in connection
                with the :inteface option.

(:generic-function-class class-name)
                Specifies that this generic function has a different
                implementation than the system-provided default.  If you
                have invented a new generic function class, this option is
                the mechanism for creating a generic function of the new
                class.  class-name is the name of a class that is capable
                of being the class of a generic function.

(:method-class class-name)
                This is used to specify that all methods for this generic
                function have a different implementation than the
                system-provided default.  If you have invented a new method
                class, this option is the mechanism for creating methods of
                the new class.  Once the def-generic-options form with this option
                is evaluated or compiled, any methods you define with
                defmethod will be implemented in the class name specified
                here.  class-name is the name of a class that is capable of
                being the class of a method.

\label Values:

The new generic function object is returned as the result.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

The function and use of {\bf def-generic-options} is closely related to the
design of the method combination mechanism and the specification of
discrimination on optional arguments. 

If a {\bf def-generic-options} form is evaluated when a generic function of the
same name is already defined, the a new generic function replaces the old.

If a {\bf def-generic-options} form is evaluated and some methods for that
generic function have parameters that are not congruent with those
listed in the {\bf def-generic-options}, an error is signalled.  

Some implementations might add other options to {\bf def-generic-options}. 
Therefore it is required that all implementations signal an error if
they observe an option that is not implemented locally.

\endcom